home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / tracerp.com / TRACE.DOC < prev    next >
Encoding:
Text File  |  1989-05-12  |  15.5 KB  |  398 lines
  1.  
  2.                            TRACE Version 1.0
  3.  
  4.                 Copyright (c) 1989  Richard W. Prescott
  5.                           All Rights Reserved
  6.  
  7.  
  8.  
  9. Files in this package:
  10.  
  11.       TRACE.DOC  - This file
  12.       TRACE.PAS  - TRACE Version 1.0 (Pascal/Assembly Source)
  13.       TRACE.TPU  - TRACE Version 1.0 (Compiled w Turbo Version 5.0)
  14.       TRACE.TP4  - TRACE Version 1.0 (Compiled w Turbo Version 4.0)
  15.      DEMOTRC.PAS - Main demonstration using TRACE
  16.      NESTTRC.PAS - Demonstration using a nested Trace routine
  17.  
  18.  
  19.  
  20. The following topics are discussed in this file:
  21.  
  22. 1. Overview
  23. 2. Using TRACE
  24. 3. Disclaimer
  25. 4. Terms and Conditions
  26. 5. TP&Asm/TP&Asm-M
  27.  
  28.  
  29.  
  30.  
  31. 1. Overview
  32.  
  33.  
  34. This package provides a powerful "trap on condition" debugging 
  35. capability for use with Turbo Pascal Versions 4.0 and 5.0.  Using 
  36. TRACE, you can designate any standard Pascal procedure which is 
  37. either  1) global, or  2) local to the current procedure, to be 
  38. executed between every two program instructions.  This means that 
  39. you can trap any condition which can be described using Pascal 
  40. statements (as well as Inline and TP&Asm assembly statements), 
  41. including:
  42.  
  43.  o One or more Pascal variables or absolute memory locations 
  44.    changed
  45.  
  46.  o One or more Pascal variables or absolute memory locations 
  47.    equal to specified value(s)
  48.  
  49.  o Value of Pascal variable between two other Pascal variables
  50.    or within specified range
  51.  
  52.  o CPU register equal to specified value
  53.  
  54.    (etc)
  55.  
  56. You can designate precisely where within your program to activate 
  57. and deactivate the trace, and different parts of your program can 
  58. have different Trace routines.  When the specified condition is
  59. detected, you can specify exactly what action should be taken, again 
  60. using any action which you can describe using Pascal statements,
  61. including:
  62.  
  63.  o Write a specified list of variables to the screen and continue 
  64.    tracing
  65.  
  66.  o Write a specified list of variables to a file and continue 
  67.    tracing
  68.  
  69.  o Write the current Cs:Ip and register values to the screen or 
  70.    a file and continue tracing
  71.  
  72.  o Release control to the IDE or an external debugger, and use
  73.    the features of the debugger to inspect variables and/or step
  74.    further through the program
  75.  
  76.  o Display message and wait for response (Readln/ReadKey).  Based
  77.    on response, reset certain variables and/or continue tracing,
  78.    switch to the IDE or an external debugger, or halt execution
  79.  
  80.    (etc)
  81.  
  82.  
  83. TRACE can be used from within the Version 4.0 or 5.0 Integrated 
  84. Development Environment (IDE), or within a program which is 
  85. compiled to disk and is run from DOS or any standard external 
  86. debugger.  
  87.  
  88. In a typical application, a program which is not operating properly 
  89. exhibits a certian unexpected behavior, say for example the value
  90. of the variable NeverZero somehow becomes zero and eventually causes
  91. a Run-Time divide error.  Using the following simple trace routine,
  92. you can easily find the statement that is causing the problem:
  93.  
  94.   PROCEDURE CheckForZero;
  95.   BEGIN
  96.     IF NeverZero = 0 THEN TRelease; {- Release to Debugger    -}
  97.     TReturn;                        {- Else return from Trace -}
  98.   END; {PROCEDURE CheckForZero}
  99.  
  100. If you are using the Version 5.0 IDE, you will be dropped into the
  101. IDE debugger at the first Pascal line following the line where
  102. NeverZero was set to zero.  You can now examine other variables 
  103. and/or use F7/F8 etc to trace further.  If you are using an external 
  104. debugger such as DEBUG, D86, or Turbo Debugger, you will be dropped 
  105. into the external debugger at the first assembly statement following 
  106. the statement which set NeverZero to zero.
  107.  
  108. Note that any program which is compiled with TRACE can also be run
  109. directly from DOS, in which case TRelease will simply deactivate the 
  110. current Trace.  This would normally be useful only if your Trace 
  111. routine writes values to the screen or a file.  
  112.  
  113.  
  114.  
  115.  
  116. 2. Using TRACE
  117.  
  118.  
  119. To use this package, simply place "TRACE" in the uses clause of 
  120. the program or unit you are debugging, construct an appropriate 
  121. Trace routine, and specify where the Trace routine will be active
  122. using TraceOn and TraceOff.  These steps are described at greater 
  123. length below.  For examples of working trace routines, please see 
  124. the files DEMOTRC.PAS and NESTTRC.PAS.
  125.  
  126. If you find this package useful you may wish to move it into your
  127. TURBO.TPL file.  Please see your reference manual for instructions
  128. on using the utility program TPUMOVER.
  129.  
  130.  
  131. Constructing a Trace Routine
  132.  
  133. The Trace Routine should be a Procedure which takes 0 parameters
  134. and which IN ALL CASES exits with a call to the (assembly) inline
  135. directive TReturn or to the procedure TRelease.  The body of the
  136. procedure should check for a user-defined condition and exit via
  137. TReturn until that condition is detected.  The routine should then
  138. take a user-defined action and exit with TReturn (to continue the
  139. Trace), TRelease (to transfer control to the Version 5.0 IDE or an 
  140. external debugger), or Halt (to terminate the program).  
  141.  
  142. Thus:
  143.  
  144.   PROCEDURE TraceProc;
  145.   BEGIN
  146.     IF   <..user-defined condition..> 
  147.     THEN BEGIN
  148.            <..user-defined trace action..> 
  149.          END; 
  150.     TReturn; {- IN ALL CASES exit via TReturn or TRelease -}
  151.   END; {PROCEDURE TraceProc}
  152.  
  153. The Trace procedure may freely reference any Pascal identifiers
  154. which are known at the point where the Trace is activated.  If the
  155. Trace procedure references ANY identifier which is not global, 
  156. however, then it MUST be placed immediately preceding the BEGIN
  157. block in which it is activated.  Thus, in the following:
  158.  
  159.   PROCEDURE GlobalProc;
  160.     Var Local1 ...
  161.     PROCEDURE NestedProc;
  162.       Var Local2 ...
  163.       PROCEDURE MoreNested; BEGIN .. END;
  164.       PROCEDURE NeedToTrace;
  165.         Var Local3 ...
  166.                                                   Position
  167.         PROCEDURE TraceProc; BEGIN .. END;   <--- Trace Procedure
  168.         BEGIN {PROCEDURE NeedToTrace}             Here
  169.           :
  170.           TraceOn(@TraceProc);
  171.           :
  172.         END;  {PROCEDURE NeedToTrace}
  173.  
  174. TraceProc must be positioned as indicated, local to the procedure
  175. in which the Trace is activated.  It can then make reference to 
  176. any of the local variables shown above.  If the Trace procedure 
  177. references only global identifiers, then its placement is not 
  178. crucial, except that it must reside in the same module (program 
  179. or unit) as the block in which it is activated.
  180.  
  181.  
  182. Activating the Trace
  183.  
  184. Tracing is activated by a call to TraceOn, as follows:
  185.  
  186.           TraceOn(@TraceProc);
  187.  
  188. where TraceProc is the name of the Pascal Trace procedure, and
  189. "@" is the "address of" operator.  As noted above, the Trace 
  190. procedure must reside in the same module as the block in which it
  191. is activated, and must contain at least one TReturn call before the 
  192. standard procedure exit code.  If an invalid Trace procedure is 
  193. detected, a Run-Time Error will be generated at the invalid TraceOn 
  194. call.
  195.  
  196. There can be at most one Trace active at any one time.  Attempting 
  197. to activate a second simultaneous Trace will also cause a Run-Time 
  198. Error.
  199.  
  200.  
  201. Deactivating the Trace
  202.  
  203. Tracing can be deactivated either from within the subject code or
  204. from within the Trace procedure itself by calling the procedure
  205. TraceOff, which takes no parameters:
  206.  
  207.           TraceOff;
  208.  
  209. Every trace procedure must be deactivated by the end of the block
  210. (procedure or function) in which it is activated, except that a
  211. global Trace routine which is activated in the main program block 
  212. does not need to be deactivated.  Normal or abnormal (Run-Time 
  213. Error) program termination automatically terminates the Trace and 
  214. restores the Interrupt 01 vector.
  215.  
  216. Tracing can also be deactivated by transferring control to the IDE
  217. or an external debugger using the procedure TRelease, which takes 
  218. no parameters:
  219.  
  220.           TRelease;
  221.  
  222. The debugger will assume control within the subject code (not the
  223. Trace routine) at the next Pascal line (for the Version 5.0 IDE 
  224. debugger) or the next assembly statement (for all other debuggers) 
  225. to be executed.
  226.  
  227. TRelease should only be called from within an active Trace routine.
  228. Attempting to call TRelease in any other situation will generate a
  229. Run-Time Error.
  230.  
  231. Finally, if the IDE or an external debugger takes control as a 
  232. result of a conditional break it will reinstall its own Interrupt
  233. 01 handler, which effectively terminates the trace.  It follows
  234. that although you can effectively use both conditional breaks and 
  235. Trace routines in the same program, you can not automatically 
  236. restart from a conditional break with Trace active.  You can if 
  237. you wish insert a TraceOff and another TraceOn following the
  238. conditional breakpoint to resume tracing after the break.
  239.  
  240.  
  241. Run-Time Error messages
  242.  
  243. This package includes an interesting feature in that it attempts 
  244. to determine if it is being used correctly.  If an invalid Trace 
  245. procedure or an attempt to "nest" TraceOn calls is detected, the 
  246. TRACE unit will display a description of the error and wait for you 
  247. to press a key.  After you press any key, a Run-Time error message 
  248. will display the Segment:Offset of the invalid TraceOn call.  If 
  249. you were executing from the Version 5.0 IDE, the invalid call will 
  250. be highlighted and the cursor will be positioned automatically at 
  251. the beginning of the line containing it.  (If you were executing 
  252. from DOS, the Version 4.0 IDE or an external debugger, you can 
  253. load the program into the IDE and use the Find Error option as 
  254. described in your reference manual).  Note that unlike the Version 
  255. 5.0 RunError statement, this system can detect an error from within 
  256. a {$D-} Unit, and it signals the Run-Time error address of the 
  257. invalid procedure CALL rather than the address (within the Unit) 
  258. where the error was detected.  The error displayed for an invalid 
  259. TraceOn or TRelease call is always number 204,  "Invalid Pointer 
  260. Operation".
  261.  
  262. While it is hoped that this precaution will help to keep you from 
  263. "shooting yourself in the foot" with this package, please note that 
  264. it is impossible to prevent all possible user errors.  In particular, 
  265. the TRACE unit cannot detect invalid TReturn calls.  TReturn should 
  266. only be used within a valid Trace procedure, and attempting to use 
  267. it in any other situation will almost certainly cause a program or 
  268. system crash.
  269.  
  270.  
  271.  
  272.  
  273. 3. DISCLAIMER OF WARRANTY
  274.  
  275.  
  276. This software and accompanying documentation are provided "as is"
  277. and without warranties as to performance or merchantability.
  278.  
  279. This package is provided without any express or implied warranties
  280. whatsoever.  Because of the diversity of conditions and hardware
  281. under which this package may be used, no warranty of fitness for a
  282. particular purpose is offered.  The user is advised to test the
  283. package thoroughly before relying on it.  THE USER MUST ASSUME THE
  284. ENTIRE RISK OF USING THE PACKAGE.
  285.  
  286.  
  287.  
  288.  
  289. 4. Terms and Conditions
  290.  
  291.  
  292. TRACE Version 1.0 is copyrighted as indicated above.  You may 
  293. however share this package and/or upload it to bulletin boards
  294. as long as no fee is charged.  User's groups and PD/shareware
  295. distributors may charge a nominal fee, not to exceed $8, provided
  296. it is accurately represented as payment for their services, not
  297. payment for the software.  In any case, the original unmodified
  298. files must all be present.
  299.  
  300. There is no user fee requested for use of this package.  If you
  301. like it, send me a message about it.  Please report problems or 
  302. suggestions to me at the address listed in section 5, or to my 
  303. CompUServe mailbox [76656,2476].
  304.  
  305. If you REALLY like it, consider registering TP&Asm (described in
  306. the following section).  While it might be possible to convert this 
  307. package into standard inline and external statements, it would not 
  308. have been developed without TP&Asm.  By removing the restrictions 
  309. on when and where you can use assembly language, TP&Asm makes it 
  310. easy to design truly innovative Pascal & assembly applications.
  311. (Admittedly, TRACE is an unusual application that uses techniques
  312. you may not need in your programs.  But TP&Asm will simplify the
  313. design of ALL your assembly projects, whether unusual or routine).
  314.  
  315.  
  316.  
  317.  
  318. 5. TP&Asm/TP&Asm-M
  319.  
  320.  
  321. TP&Asm is a small assembler which runs Turbo 4.0/5.0 (Integrated
  322. Environment or TPC) as a subprocess and permits you to place
  323. assembly language statements directly into your Pascal source code
  324. in blocks beginning with the keywords "Assemble" and/or "Internal".
  325.  
  326. TP&Asm provides the convenience and flexibility of having "live"
  327. assembly language in your programs which can be modified and
  328. immediately recompiled with no need to exit and reassemble.  You
  329. have complete freedom to place assembly language anywhere in your
  330. program, freely mix Pascal and assembly blocks, freely transfer
  331. between Pascal and assembly blocks via Call/Jump/Loop/Goto to any
  332. Pascal or assembly label, make direct Call, Jmp and Offset
  333. references to Pascal Proc/Functions, and make simplified Pascal
  334. style references to your Pascal and assembly variables and
  335. parameters.  Units compiled with TP&Asm can be distributed and 
  336. Used independent of TP&Asm.  
  337.  
  338. The resulting ASSEMBLY Development Environment is identical to your 
  339. PASCAL Development Environment.  It provides fast assembly with no 
  340. additional disk access, and reports assembly syntax errors on the 
  341. standard Turbo error line with cursor placed on the error.  It 
  342. accepts the standard syntax of both MASM and A86, but also provides 
  343. certain enhancements such as the placement of named data in the 
  344. Code Segment.  
  345.  
  346. With Turbo Version 5.0, you can trace your assembly code line by 
  347. line in the IDE.  Using the record variable CPU defined in the unit 
  348. ASMWATCH (included), you can Watch, Evaluate, and Modify the CPU 
  349. registers and flags during the trace.  
  350.  
  351. TP&Asm Version 2.0 can be purchased from me at the address given
  352. below for $49 plus $3 P&H.
  353.  
  354. A shareable Memory Mode version called TP&Asm-M is also available.
  355. The distinction between TP&Asm and TP&Asm-M is that TP&Asm-M is 
  356. intended for developing and debugging assembly language in the IDE, 
  357. but not for final compilation.  You can compile to Memory (with the 
  358. standard Turbo style interactive syntax error detection) and Trace 
  359. your assembly code in the IDE with full capability to Watch, 
  360. Evaluate, and Modify the CPU registers and Flags - then convert to 
  361. INLINE or EXTERNAL after the code is fully developed.  TP&Asm-M's 
  362. INTERNAL statement and its support of the standard syntax of MASM, 
  363. A86, and INLINE.COM simplifies this conversion.  
  364.  
  365. The TP&Asm-M distribution disk can be ordered from me for $5 plus 
  366. $3 P&H, with the $5 being credited toward subsequent registration 
  367. of TP&Asm or TP&Asm-M.  It can also be downloaded from the IBMPRO 
  368. or BPROGA forums on CompUServe.  Look for the archives TP-ASM and 
  369. TPA2-R ( May be ".ARC" or ".ZIP" ).  Registration for TP&Asm-M is 
  370. $19.
  371.  
  372.  
  373. To order TP&Asm, please send a check or money order payable to:
  374.  
  375.                       Richard W. Prescott
  376.                       724 Sauk Ridge Trail
  377.                       Madison, WI  53705
  378.  
  379. Please include the following information:
  380.  
  381.    1. Full Version number of the Turbo Pascal compiler you now use.
  382.  
  383.    2. Your registration number for that compiler.
  384.  
  385.    3. If you obtained TP&Asm-M from a bulletin board:
  386.       3a. Area code and phone number of that bulletin board
  387.       3b. Full Version number of the TP&Asm-M version you have
  388.       3c. Directory Date of the README file
  389.  
  390.  
  391.  
  392.  
  393.  
  394. TRACE.TPU was compiled and assembled using TP&Asm Version 2.0 
  395. running Turbo Pascal Version 5.0.  
  396. TRACE.TP4 was compiled and assembled using TP&Asm Version 2.0 
  397. running Turbo Pascal Version 4.0.  
  398.